package org.jeecg.weixin.cp.api;

import org.jeecg.weixin.common.error.WxErrorException;
import org.jeecg.weixin.cp.bean.oa.WxCpOaSchedule;

import java.util.List;

/**
 * 企业微信日程接口. 官方文档：https://work.weixin.qq.com/api/doc/90000/90135/93648
 *
 * @author <a href="https://github.com/binarywang">Binary Wang</a>
 */
public interface WxCpOaScheduleService {
	/**
	 * 创建日程
	 * <p>
	 * 该接口用于在日历中创建一个日程。
	 * <p>
	 * 请求方式： POST（HTTPS） 请求地址：
	 * https://qyapi.weixin.qq.com/cgi-bin/oa/schedule/add?access_token=ACCESS_TOKEN
	 *
	 * @param schedule
	 *            the schedule
	 * @param agentId
	 *            授权方安装的应用agentid。仅旧的第三方多应用套件需要填此参数
	 * @return 日程ID string
	 * @throws WxErrorException
	 *             the wx error exception
	 */
	String add(WxCpOaSchedule schedule, Integer agentId) throws WxErrorException;

	/**
	 * 更新日程
	 * <p>
	 * 该接口用于在日历中更新指定的日程。
	 * <p>
	 * 注意，更新操作是覆盖式，而不是增量式 不可更新组织者和日程所属日历ID
	 * <p>
	 * 请求方式： POST（HTTPS） 请求地址：
	 * https://qyapi.weixin.qq.com/cgi-bin/oa/schedule/update?access_token=ACCESS_TOKEN
	 *
	 * @param schedule
	 *            the schedule
	 * @throws WxErrorException
	 *             the wx error exception
	 */
	void update(WxCpOaSchedule schedule) throws WxErrorException;

	/**
	 * 获取日程详情
	 * <p>
	 * 该接口用于获取指定的日程详情。
	 * <p>
	 * 请求方式： POST（HTTPS） 请求地址：
	 * https://qyapi.weixin.qq.com/cgi-bin/oa/schedule/get?access_token=ACCESS_TOKEN
	 *
	 * @param scheduleIds
	 *            the schedule ids
	 * @return the details
	 * @throws WxErrorException
	 *             the wx error exception
	 */
	List<WxCpOaSchedule> getDetails(List<String> scheduleIds) throws WxErrorException;

	/**
	 * 取消日程 该接口用于取消指定的日程。
	 * <p>
	 * 请求方式： POST（HTTPS） 请求地址：
	 * https://qyapi.weixin.qq.com/cgi-bin/oa/schedule/del?access_token=ACCESS_TOKEN
	 *
	 * @param scheduleId
	 *            日程id
	 * @throws WxErrorException
	 *             the wx error exception
	 */
	void delete(String scheduleId) throws WxErrorException;

	/**
	 * 获取日历下的日程列表 该接口用于获取指定的日历下的日程列表。 仅可获取应用自己创建的日历下的日程。
	 * <p>
	 * 请求方式： POST（HTTPS） 请求地址：
	 * https://qyapi.weixin.qq.com/cgi-bin/oa/schedule/get_by_calendar?access_token=ACCESS_TOKEN
	 *
	 * @param calId
	 *            日历ID
	 * @param offset
	 *            分页，偏移量, 默认为0
	 * @param limit
	 *            分页，预期请求的数据量，默认为500，取值范围 1 ~ 1000
	 * @return the string
	 * @throws WxErrorException
	 *             the wx error exception
	 */
	List<WxCpOaSchedule> listByCalendar(String calId, Integer offset, Integer limit) throws WxErrorException;
}
